package com.zenithmind.document.mapper;

import com.baomidou.mybatisplus.core.mapper.BaseMapper;
import com.zenithmind.document.pojo.domain.DocumentStatistics;
import org.apache.ibatis.annotations.Mapper;
import org.apache.ibatis.annotations.Param;

import java.util.List;

/**
 * 文档统计映射器
 * 遵循单一职责原则：专注于文档统计数据访问
 * 遵循依赖倒置原则：定义抽象的数据访问接口
 * 
 * @author ZenithMind Team
 * @since 2025-01-09
 */
@Mapper
public interface DocumentStatisticsMapper extends BaseMapper<DocumentStatistics> {

    /**
     * 根据文档ID查询统计信息
     * 
     * @param documentId 文档ID
     * @return 统计信息
     */
    DocumentStatistics selectByDocumentId(@Param("documentId") String documentId);

    /**
     * 增加文档查看次数
     * 
     * @param documentId 文档ID
     * @param userId 用户ID
     * @return 影响行数
     */
    Integer incrementViewCount(@Param("documentId") String documentId, @Param("userId") String userId);

    /**
     * 增加文档下载次数
     * 
     * @param documentId 文档ID
     * @param userId 用户ID
     * @return 影响行数
     */
    Integer incrementDownloadCount(@Param("documentId") String documentId, @Param("userId") String userId);

    /**
     * 增加文档分享次数
     * 
     * @param documentId 文档ID
     * @param userId 用户ID
     * @return 影响行数
     */
    Integer incrementShareCount(@Param("documentId") String documentId, @Param("userId") String userId);

    /**
     * 增加文档收藏次数
     * 
     * @param documentId 文档ID
     * @return 影响行数
     */
    Integer incrementFavoriteCount(@Param("documentId") String documentId);

    /**
     * 减少文档收藏次数
     * 
     * @param documentId 文档ID
     * @return 影响行数
     */
    Integer decrementFavoriteCount(@Param("documentId") String documentId);

    /**
     * 更新文档评分
     * 
     * @param documentId 文档ID
     * @param rating 评分
     * @return 影响行数
     */
    Integer updateDocumentRating(@Param("documentId") String documentId, @Param("rating") Double rating);

    /**
     * 查询系统统计信息
     * 
     * @return 统计信息
     */
    Object selectSystemStatistics();

    /**
     * 查询用户统计信息
     * 
     * @param userId 用户ID
     * @return 统计信息
     */
    Object selectUserStatistics(@Param("userId") String userId);

    /**
     * 查询分类统计信息
     * 
     * @param categoryId 分类ID
     * @return 统计信息
     */
    Object selectCategoryStatistics(@Param("categoryId") String categoryId);

    /**
     * 查询趋势统计信息
     * 
     * @param days 天数
     * @param limit 限制数量
     * @return 统计信息列表
     */
    List<Object> selectTrendingStatistics(@Param("days") Integer days, @Param("limit") Integer limit);

    /**
     * 查询热门统计信息
     * 
     * @param type 统计类型
     * @param limit 限制数量
     * @return 统计信息列表
     */
    List<Object> selectPopularStatistics(@Param("type") String type, @Param("limit") Integer limit);

    /**
     * 查询仪表板统计信息
     * 
     * @param userId 用户ID
     * @return 统计信息
     */
    Object selectDashboardStatistics(@Param("userId") String userId);

    /**
     * 查询实时统计信息
     * 
     * @return 统计信息
     */
    Object selectRealTimeStatistics();

    /**
     * 查询对比统计信息
     * 
     * @param type 对比类型
     * @param period1 时间范围1
     * @param period2 时间范围2
     * @return 统计信息
     */
    Object selectComparisonStatistics(@Param("type") String type, @Param("period1") String period1, @Param("period2") String period2);

    /**
     * 导出统计数据
     * 
     * @param type 统计类型
     * @param startDate 开始日期
     * @param endDate 结束日期
     * @return 统计数据
     */
    Object exportStatistics(@Param("type") String type, @Param("startDate") String startDate, @Param("endDate") String endDate);

    /**
     * 生成统计报告
     * 
     * @param reportType 报告类型
     * @param startDate 开始日期
     * @param endDate 结束日期
     * @return 报告数据
     */
    Object generateStatisticsReport(@Param("reportType") String reportType, @Param("startDate") String startDate, @Param("endDate") String endDate);

    /**
     * 同步文档统计数据
     * 
     * @param documentId 文档ID
     * @return 影响行数
     */
    Integer syncDocumentStatistics(@Param("documentId") String documentId);

    /**
     * 清理过期统计数据
     * 
     * @param retentionDays 保留天数
     * @return 清理数量
     */
    Integer cleanupExpiredStatistics(@Param("retentionDays") Integer retentionDays);

    /**
     * 批量更新统计数据
     * 
     * @param statisticsList 统计数据列表
     * @return 影响行数
     */
    Integer batchUpdateStatistics(@Param("list") List<DocumentStatistics> statisticsList);

    /**
     * 查询热门文档
     * 
     * @param type 排序类型（view, download, favorite等）
     * @param limit 限制数量
     * @return 文档列表
     */
    List<Object> selectHotDocuments(@Param("type") String type, @Param("limit") Integer limit);

    /**
     * 查询文档排行榜
     * 
     * @param type 排行类型
     * @param categoryId 分类ID（可选）
     * @param limit 限制数量
     * @return 排行榜数据
     */
    List<Object> selectDocumentRanking(@Param("type") String type, @Param("categoryId") String categoryId, @Param("limit") Integer limit);

    /**
     * 查询用户活跃度统计
     * 
     * @param days 统计天数
     * @param limit 限制数量
     * @return 用户活跃度数据
     */
    List<Object> selectUserActivityStatistics(@Param("days") Integer days, @Param("limit") Integer limit);

    /**
     * 查询文档类型分布统计
     * 
     * @return 类型分布数据
     */
    List<Object> selectDocumentTypeDistribution();

    /**
     * 查询文档大小分布统计
     * 
     * @return 大小分布数据
     */
    List<Object> selectDocumentSizeDistribution();

    /**
     * 查询访问时间分布统计
     * 
     * @param days 统计天数
     * @return 时间分布数据
     */
    List<Object> selectAccessTimeDistribution(@Param("days") Integer days);

    /**
     * 查询搜索关键词统计
     * 
     * @param days 统计天数
     * @param limit 限制数量
     * @return 关键词统计数据
     */
    List<Object> selectSearchKeywordStatistics(@Param("days") Integer days, @Param("limit") Integer limit);

    /**
     * 查询文档评分分布
     * 
     * @return 评分分布数据
     */
    List<Object> selectRatingDistribution();

    /**
     * 查询月度统计数据
     * 
     * @param year 年份
     * @return 月度统计数据
     */
    List<Object> selectMonthlyStatistics(@Param("year") Integer year);

    /**
     * 查询年度统计数据
     * 
     * @param years 年份数量
     * @return 年度统计数据
     */
    List<Object> selectYearlyStatistics(@Param("years") Integer years);
}
